package com.googlecode.dgwt.client.dojo.data.listener;

import com.googlecode.dgwt.client.dojo.data.base.ModeledStore;
import com.googlecode.dgwt.client.dojo.data.base.Store;
import com.googlecode.dgwt.client.dojo.data.model.StoreColumn;
import com.googlecode.dgwt.client.dojo.data.model.StoreModel;

/**
 * Listener that cares about the columns operations done on a {@link StoreModel}. <br/>
 * <br/>
 * Events that requires to update the store items data on screen:
 * <ul>  
 *   <li>{@link #onColumnAdded(int, StoreColumn)}</li>
 *   <li>{@link #onColumnRemoved(StoreColumn)}</li>
 *   <li>{@link #onColumnReplaced(int, StoreColumn, StoreColumn)}</li>
 *   <li>{@link #onColumnRefresh(StoreColumn)}</li>
 * </ul>
 * 
 * @see ModeledStore
 * 
 * @author wellsantos@wellsantos.com
 * @since 0.01
 */
public interface ModelListener<Item> extends AttachListener<Store<Item>> {

    /**
     * Event fired when a column has been added.
     * 
     * @param column
     *            the column
     */
    public void onColumnAdded(StoreColumn<Item, ?> column);

    /**
     * Event fired when a column has been removed.
     * 
     * @param column
     *            the column
     */
    public void onColumnRemoved(StoreColumn<Item, ?> column);

    /**
     * Event fired when a column has been changed. <br/>
     * It means that column properties like title or width has changed. <br/>
     * Note that, only in this case, the data in the store should <b>not</b> be update on screen. <br/>
     * <br/>
     * See {@link ModelListener} to get a list of methods that needs data to be updated.
     * 
     * @param column
     *            the column that has changed
     */
    public void onColumnChanged(StoreColumn<Item, ?> column);

    /**
     * Event fired when a column has been replaced by another one.
     * 
     * @param columnIndex
     *            the column index
     * @param oldColumn
     *            column that was removed
     * @param newColumn
     *            column that was added
     */
    public void onColumnReplaced(int columnIndex, StoreColumn<Item, ?> oldColumn, StoreColumn<Item, ?> newColumn);
    
    /**
     * Event fired when all the items on the store should be updated at a column. 
     * 
     * @param column
     *            the column that needs to refresh
     */
    public void onColumnRefresh(StoreColumn<Item, ?> column);
}
